#lang scribble/doc


@(require scribble/manual)
@(require rosetta)


@title{Rosetta}
@declare-exporting[Rosetta]


@section{Coords}

Coords are...


@subsection{Cartesian}

@defproc[(xyz (x number?) (y number?) (z number?)) coord?]{
Creates a @racket[coord?] using Cartesian coordinates, where
@racket[x] is the @racket[coord?] distance in the X-axis,
@racket[y] is the @racket[coord?] distance in the Y-axis, and
@racket[z] is the @racket[coord?] distance in the Z-axis.
}

@defproc*[(((xy (x number?) (y number?)) coord?)
           ((xy (c coord?) (x number?) (y number?)) coord?))]{
The first version creates a @racket[coord?] using Cartesian coordinates.
Equivalent to @racket[(xyz x y 0)].

The second version creates a @racket[coord?] using Cartesian coordinates with @racket[z] value from @racket[c].
Equivalent to @racket[(x y (xyz-z c))].
}

@defproc*[(((yz (y number?) (z number?)) coord?)
           ((yz (c coord?) (y number?) (z number?)) coord?))]{
The first version creates a @racket[coord?] using Cartesian coordinates.
Equivalent to @racket[(xyz 0 y z)].

The second version creates a @racket[coord?] using Cartesian coordinates with @racket[x] value from @racket[c].
Equivalent to @racket[(xyz (xyz-x c) y z)].
}
                                                             
@defproc*[(((xz (x number?) (z number?)) coord?)
           ((xz (c coord?) (x number?) (z number?)) coord?))]{
The first version creates a @racket[coord?] using Cartesian coordinates.
Equivalent to @racket[(xyz x 0 z)].

The second version creates a @racket[coord?] using Cartesian coordinates with @racket[y] value from @racket[c]
Equivalent to @racket[(xyz x (xyz-y c) z)].
}

@defproc*[(((x (x number?)) coord?)
           ((x (c coord?) (x number?)) coord?))]{
The first version creates a @racket[coord?] using Cartesian coordinates.
Equivalent to @racket[(xyz x 0 0)].

The second version creates a @racket[coord?] using Cartesian coordinates with @racket[y] and @racket[z] values from @racket[c].
Equivalent to @racket[(xyz x (xyz-y c) (xyz-z c))].
}
                                                
@defproc*[(((y (y number?)) coord?)
           ((y (c coord?) (y number?)) coord?))]{
The first version creates a @racket[coord?] using Cartesian coordinates
Equivalent to @racket[(xyz 0 y 0)].

The second version creates a @racket[coord?] using Cartesian coordinates with @racket[x] and @racket[z] values from @racket[c]
Equivalent to @racket[(xyz (xyz-x c) y (xyz-z c))].
}
                                                
@defproc*[(((z (z number?)) coord?)
           ((z (c coord?) (z number?)) coord?))]{
The first version creates a @racket[coord?] using Cartesian coordinates
Equivalent to @racket[(xyz 0 0 z)].

The second version creates a @racket[coord?] using Cartesian coordinates with @racket[x] and @racket[y] values from @racket[c]
Equivalent to @racket[(xyz (xyz-x c) (xyz-y c) z)].
}
                                                
@defproc[(xyz-x (c coord?)) number?]{
Returns the Cartesian @racket[x] value of @racket[c].
}

@defproc[(xyz-y (c coord?)) number?]{
Returns the Cartesian @racket[y] value of @racket[c].
}

@defproc[(xyz-z (c coord?)) number?]{
Returns the Cartesian @racket[z] value of @racket[c].
}

@defproc[(xyz-r (c coord?)) number?]{
Returns the length of @racket[c].
}


@subsection{Cylindrical}

@defproc[(cyl (rho distance?) (phi number?) (z number?)) coord?]{
Creates a @racket[coord?] using cylindrical coordinates, where
@racket[rho] is the distance of the @racket[coord?] projection in the XY-plane,
@racket[phi] is the angle in the XY-plane with the X-axis, and
@racket[z] is equivalent to the Cartesian @racket[z].
}

@defproc[(cyl-rho (c coord?)) distance?]{
Returns the cylindrical @racket[rho] value of @racket[c].
                        
In @racket[rosetta-racket] lang, use @racket[cyl-ρ] instead.

In @racket[rosetta-javascript] lang, use @racket[cylRho] instead.
}

@defproc[(cyl-phi (c coord?)) number?]{
Returns the cylindrical @racket[phi] value of @racket[c].
}

@defproc[(cyl-z (c coord?)) number?]{
Returns the cylindrical @racket[z] value of @racket[c].
}


@subsection{Polar}

Polar coordinates are a particular case of cylindrical coordinates,
where the value of @racket[z] is @racket[0].

@defproc[(pol (rho distance?) (phi number?)) coord?]{
Creates a @racket[coord?] using polar coordinates.
Equivalent to @racket[(cyl rho phi 0)].
}

@defproc[(pol-rho (c coord?)) distance?]{
Returns the polar @racket[rho] value of @racket[c].
Equivalent to @racket[cyl-rho] but the @racket[z] value of @racket[c] is ignored.
}

@defproc[(pol-phi (c coord?)) number?]{
Returns the polar @racket[phi] value of @racket[c].
Equivalent to @racket[cyl-phi] but the @racket[z] value of @racket[c] is ignored.
}


@subsection{Spherical}

@defproc[(sph (r distance?) (phi number?) (th number?)) coord?]{
Creates a @racket[coord?] using spherical coordinates, where
@racket[r] is the distance of the @racket[coord?],
@racket[phi] is the angle in the XY-plane with the X-axis, and
@racket[th] is the angle in the vertical plane defined by @racket[phi] with the Z-axis.
}

@defproc[(sph-r (c coord?)) distance?]{
Returns the spherical @racket[r] value of @racket[c].
Equivalent to @racket[xyz-r].
}

@defproc[(sph-phi (c coord?)) number?]{
Returns the spherical @racket[phi] value of @racket[c].
}

@defproc[(sph-th (c coord?)) number?]{
Returns the spherical @racket[th] value of @racket[c].
}


@subsection{Constants}

@defidform[u0]{
A convenience name for the origin, e.g., @racket[(xyz 0 0 0)].
}


@defidform[ux]{
A convenience name for the X-axis unit vector, e.g., @racket[(xyz 1 0 0)].
}

@defidform[uy]{
A convenience name for the Y-axis unit vector, e.g., @racket[(xyz 0 1 0)].
}

@defidform[uz]{
A convenience name for the Z-axis unit vector, e.g., @racket[(xyz 0 0 1)].
}


@defidform[uxy]{
A convenience name for the addition of @racket[ux] and @racket[uy], e.g., @racket[(xyz 1 1 0)].
}

@defidform[uyz]{
A convenience name for the addition of @racket[uy] and @racket[uz], e.g., @racket[(xyz 0 1 1)].
}

@defidform[uxz]{
A convenience name for the addition of @racket[ux] and @racket[uz], e.g., @racket[(xyz 1 0 1)].
}

@defidform[uxyz]{
A convenience name for the addition of @racket[ux], @racket[uy] and @racket[uz], e.g., @racket[(xyz 1 1 1)].
}


@subsection{Predicates}

@defproc[(coord? (c any/c)) boolean?]{
Tests if @racket[c] is a @racket[coord?].
}

@defproc[(u0? (c any/c)) boolean?]{
Tests if @racket[c] is a @racket[coord?] and if it is the origin.
}